                              Sudoku Solver
                              Version 1.00
                        Release date: 2009-11-15

                                  by

                             Eric Oulashin
                     Sysop of Digital Distortion BBS
                 BBS internet address: digdist.bbsindex.com
                     Email: eric.oulashin@gmail.com



This file describes Sudoku Solver, a BBS door program for Synchronet
that can solve Sudoku puzzles.

Contents
========
1. Introduction
2. Installation & Setup
3. Revision History


1. Introduction
===============
This is a door program for Synchronet BBSs that can solve a Sudoku puzzle.
The user can input the puzzle numbers and then have the door program solve
the puzzle.  ANSI and ASCII terminals are supported.

This door was written in JavaScript, and it uses a brute-force algorithm
that can solve any Sudoku puzzle.  The algorithm was obtained from the
following Wikipedia page describing the algorithmics of Sudoku:
http://en.wikipedia.org/wiki/Algorithmics_of_sudoku

Most Sudoku puzzles solved using this algorithm fairly quickly (within
1-5 seconds); however, there are some Sudoku puzzles that take
significantly more time than others; however, I would not expect this
door to take more than 1-2 minutes to solve any Sudoku puzzle.

I have found that for solving Sudoku puzzles, JavaScript is noticeably
slower than C++ with the brute-force algorithm.  Also, for a puzzle
that is a near worst case for the brute-force algorithm, the JavaScript
version on Synchronet will abort due to a technical limitation.
Therefore, I have included a compiled solver program written in C++
that the script can use if it exists in the same directory as the
JavaScript files.  The compiled solver program uses the same
brute-force algorithm, but it is much faster.  When the compiled
solver program is in place, the JavaScript door then acts simply
as a user interface, making use of the compiled solver in the
background.


2. Installation & Setup
=======================
These are the steps for installation:
 1. Unzip the archive.  If you're viewing this file, then you've probably
    already done this. :)
 2. Place all of the .js files in a directory together.  For example,
    sbbs\xtrn\SudokuSolver
 3. Place the compiled solver program in the same directory as the .js files.
    For Windows, the solver program is solveSudokuPuzzle.exe, in the Win32
    directory from the Sudoku Solver archive.  For Linux, the solver program
    is solveSudokuPuzzle, in the Linux directory.  For other systems,
    I have also included the C++ source code for the solver program, along
    with a Makefile you can use to compile it (in the
    "solveSudokuPuzzle source code" directory).  The source code may also
    be needed for some Linux systems where my pre-compiled version can't
    run.
    I strongly recommend this step; otherwise, for puzzles that take a long
    time to solve, the JavaScript version could abort with the following
    error:
    !JavaScript  DDSudokuSolverClass.js line 91: Error: Infinite loop
    (100000000 branches) detected
 4. Set up the door on your BBS with Synchronet's configration program (SCFG).
    This is an example of how the door setup should look in SCFG:
    +[][?]----------------------------------------------------+
                           Sudoku Solver                      
    ----------------------------------------------------------
     Name                       Sudoku Solver                
     Internal Code              SUDOKU                       
     Start-up Directory         ../xtrn/SudokuSolver         
     Command Line               ?../xtrn/SudokuSolver/DDSudokuSolver.js
     Clean-up Command Line                                   
     Execution Cost             None                         
     Access Requirements                                     
     Execution Requirements                                  
     Multiple Concurrent Users  Yes                          
     Intercept Standard I/O     No                           
     Native (32-bit) Executable No                           
     Use Shell to Execute       No                           
     Modify User Data           No                           
     Execute on Event           No                           
     Pause After Execution      No                           
     BBS Drop File Type         None                         
    Place Drop File In         Node Directory               
    +----------------------------------------------------------+



3. Revision History
===================
Version  Date         Description
-------  ----         -----------
1.00     2009-11-15   First public release